SPEC-PWF-OPS · v0.1
14 June 2026
Owner: Platform team

Service operations

The ongoing loop once a device is live: a service visit's time is agreed with the customer, agreement renews on each device's own cadence, incidents resolve against the SLA that agreement sets, field engineers execute the on-site visits, and invoices issue and settle. This is the manual for the operations sub-hierarchy — five lifecycles, interlocking through a single thread: a device's maintenance agreement.

1The five lifecycles

One process per document. Service scheduling agrees a visit's time with the customer across three apps before dispatch; agreement keeps each device's maintenance agreement continuous; incident response turns a telemetry breach into a resolved alarm; field visit is the engineer's on-site execution of a scheduled visit; invoice lifecycle takes a charge from issued to paid. They begin where quote-to-cash ends — a commissioned device with its first agreement.

2How the loops interlock

The three agreement-threaded lifecycles are not independent — a device's maintenance agreement is the thread that ties them. Agreement sets the tier; incident response freezes its SLA from that tier at ticket creation; billing invoices its period. Field visit composes within incident and agreement — the engineer's execution of the visit they schedule; service scheduling sits just upstream of field visit, the propose → select negotiation that agrees that visit's time with the customer. Each loop runs on its own cadence, per device or per organization.

• Agreement → incident. A service ticket freezes its SLA from the device's agreement tier at creation (DM-19) — so the agreement a customer holds is exactly what incident response honors, even if the agreement later moves or lapses.
• Agreement → billing & sales. Agreements are per device, each with its own PeriodEnd; ahead of every period end Agreement signals Sales the renewal opportunity (agreement.expiring) and Billing the period to invoice. The derived PartnerCustomer — and its access grant — lives exactly while agreement exists.
• Upstream of the model. Incident response begins at alert.raised; the telemetry plane that evaluates thresholds sits outside Postgres (PTL-1 ⚠). Billing is organization-scoped — the riversync tenant has none — and currency always comes from the BillingProfile (THB for the reference orgs), never assumed.

3Maintenance lifecycle

Per-device agreement: attach, hold, expire, renew or move, lapse. A device can move to a new partner at its own renewal; the partner link and its access track agreement exactly. Full detail is in the maintenance drill-down (SPEC-PWF-MNT).

4Incident response

Telemetry breach → alarm → remote fix or engineer visit → resolved, with the conversation thread recording it. The ticket's SLA is frozen from the device's agreement tier at creation. Full detail is in the incident drill-down (SPEC-PWF-INC).

5Field visit

The engineer's on-site execution of the visit that incident or agreement schedules: dispatch → check-in → corrective or preventive work → parts & evidence → customer sign-off, offline-first. One source per visit — a service ticket or a maintenance plan, never both. Full detail is in the field-visit drill-down (SPEC-PWF-FLD).

6Service scheduling

Before an engineer is dispatched, the visit's time is agreed across three apps: RiverSync proposes candidate slots (Admin), constrained by the customer's standing scheduling preferences; the customer selects one (Portal); the servicing partner works the visits it services within scope (Partners). The accepted slot creates the Visit that field visit then executes. Full detail is in the scheduling drill-down (SPEC-PWF-SCH).

7Invoice lifecycle

Issued → due → paid, or escalated to accounting follow-up when overdue. Organization-scoped; currency from the BillingProfile. Full detail is in the billing drill-down (SPEC-PWF-BIL).

8Rules in play

The WF-rules that bind the operating lifecycles — the master holds the full set. Note WF-7: scope- and channel-sensitive steps defer to the single resolvers (Agreement owns partner scope, SVC-6) rather than re-deciding inline.

9Traceability & open questions

What each lifecycle realizes and the events it rides; no step stands without evidence (WF-2). The ⚠ gaps match the master ERD and PRD.

Lifecycle	Realizes	Rides events
Service scheduling	PTL-11 · ADM-7 · PAR-15 · FLD-1	visit.proposed · visit.proposal-accepted · visit.proposal-declined · visit.scheduled
Maintenance lifecycle	PRT-1 · PRT-2 · PRT-8	agreement.attached · .expiring · .renewed · .moved · partner-link.lapsed
Incident response	PTL-1 ⚠ · PTL-2 · PTL-4 · PTL-5	alert.raised · .acknowledged · ticket.created · visit.scheduled · device.command-executed
Field visit	FLD-1…9 · DM-27…31	visit.scheduled · visit.checked-in · visit.completed · maintenance.due
Invoice lifecycle	ACC-3 · ADM-3	invoice.issued · invoice.overdue

• ⚠ PTL-1 — the telemetry plane is upstream of the model. Incident response begins at alert.raised; threshold evaluation lives outside Postgres and is not a workflow step here.
• ⚠ ACC-6 — no notifications consumer. The overdue invoice emits invoice.overdue with no dunning-delivery step — the same gap onboarding's invite hits. Each loop marks the step rather than inventing a channel.
• SLA on move. When a device's agreement moves to a new partner, open tickets keep the SLA frozen at creation (DM-19) — agreement changes do not retroactively re-tier live incidents.

10Revision history

Version	Date	Changes
0.1	14 Jun 2026	First draft — the operating lifecycles become a sub-hierarchy of the workflow set (SPEC-PWF-OPS). This overview/manual joins agreement (SPEC-PWF-AGR), incident response (SPEC-PWF-INC) and invoice lifecycle (SPEC-PWF-BIL), now grouped under workflow/operate/. No change to the lifecycles themselves.
0.2	14 Jun 2026	Field visit (SPEC-PWF-FLD) joins the group as the fourth lifecycle — the engineer's on-site execution for the new Field app (SPEC-APP-FLD); composes within incident and agreement (WF-8). Now four lifecycles.
0.3	29 Jun 2026	Service scheduling (SPEC-PWF-SCH) joins as the fifth lifecycle — the propose → select negotiation across Portal · Admin · Partners that agrees a visit's time with the customer before field execution (PTL-11 · ADM-7 · PAR-15; entities VisitProposal · VisitProposalOption · SchedulingPreference, DM-57…59; Field owns scheduling, SVC-20). New §6 with its swimlane; later sections renumbered §7–§10. Now five lifecycles.